Accelerating Docker Pull in Mainland China with Registry Mirrors

Table of contents

The Problem: Network Connectivity | 问题所在：网络连接
The Solution: Registry Mirrors | 解决方案：镜像仓库加速器
Configuration: Modifying daemon.json | 配置：修改 daemon.json
- For Linux Users | 对于 Linux 用户
- For Windows/macOS Users (Using Docker Desktop) | 对于 Windows/macOS 用户（使用 Docker Desktop）
Verification | 验证
Conclusion | 结论

Pulling public container images from Docker Hub is a fundamental operation when working with Docker. However, users located in mainland China often encounter significantly slow download speeds or even complete failures when attempting to execute docker pull commands directed towards Docker Hub. This issue primarily stems from network latency and connectivity challenges associated with accessing international resources from within the region.

Fortunately, a standard and effective solution exists: configuring the Docker daemon to utilize registry mirrors. This brief guide will outline the rationale and provide the necessary steps to implement this configuration, drawing on common examples of available mirror services.

从 Docker Hub 拉取公共容器镜像是使用 Docker 时的基础操作。然而，位于中国大陆的用户在尝试执行指向 Docker Hub 的 docker pull 命令时，经常遇到下载速度极慢甚至完全失败的情况。这个问题主要源于从地区内部访问国际资源相关的网络延迟和连接挑战。

幸运的是，一个标准且有效的解决方案已经存在：配置 Docker 守护进程使用镜像仓库加速器 (registry mirrors)。本指南将概述其原理，并提供实现此配置所需的步骤，并会引用一些常见的可用镜像服务示例。

The Problem: Network Connectivity | 问题所在：网络连接

Docker Hub, the default registry for docker pull commands (e.g., docker pull ubuntu implicitly means docker pull docker.io/library/ubuntu), is globally distributed but the primary endpoints are often hosted outside mainland China. Network connections traversing long distances or international boundaries can experience high latency, packet loss, and bandwidth throttling, leading to protracted download times or connection timeouts for large files like container images.

Docker Hub，即 docker pull 命令的默认镜像仓库（例如，docker pull ubuntu 隐式地等同于 docker pull docker.io/library/ubuntu），是全球分布的，但其主要服务节点通常托管在中国大陆之外。跨越长距离或国际边界的网络连接可能会遇到高延迟、丢包和带宽限制，导致容器镜像等大文件的下载时间过长或连接超时。

The Solution: Registry Mirrors | 解决方案：镜像仓库加速器

Registry mirrors are cached copies of Docker Hub content (and sometimes other public registries) that are hosted within mainland China by cloud service providers, universities, or other organizations. When you configure your Docker daemon to use a mirror, your docker pull requests are first directed to the specified mirror URL. If the mirror has a local copy of the requested image layer, it serves it directly and quickly. If not, the mirror fetches it from Docker Hub, caches it, and then serves it to you. Subsequent requests for the same layer from other users of that mirror will then be served from the local cache.

使用镜像仓库加速器是因为它们是 Docker Hub（有时也包括其他公共仓库）内容的缓存副本，由云服务提供商、大学或其他组织托管在中国大陆境内。当你配置 Docker 守护进程使用镜像加速器时，你的 docker pull 请求会首先被导向指定的镜像 URL。如果镜像有请求的镜像层的本地副本，它会直接、快速地为你提供。如果本地没有，镜像会从 Docker Hub 拉取，进行缓存，然后再提供给你。该镜像的其他用户后续对同一个镜像层的请求，就可以直接从本地缓存获取。

This approach significantly reduces the impact of international network issues by utilizing high-speed domestic network links between your Docker host and the mirror server.

这种方法利用你的 Docker 主机与镜像服务器之间的高速国内网络连接，显著降低了国际网络问题的影响。

Configuration: Modifying daemon.json | 配置：修改 daemon.json

The standard method to configure one or more registry mirrors is by editing the Docker daemon configuration file, daemon.json. This file is typically located in /etc/docker/ on Linux systems, or can be configured via the Docker Desktop application settings on Windows and macOS.

配置一个或多个镜像仓库加速器的标准方法是编辑 Docker 守护进程的配置文件 daemon.json。在 Linux 系统上，此文件通常位于 /etc/docker/；在 Windows 和 macOS 上，则可以通过 Docker Desktop 应用的设置界面进行配置。

For Linux Users | 对于 Linux 用户

Locate or Create daemon.json: The file should be located at /etc/docker/daemon.json. If it doesn't exist, create it. Requires root privileges.

找到或创建 daemon.json：文件应位于 /etc/docker/daemon.json。如果文件不存在，请创建它。这需要 root 权限。

Edit the file: Add or modify the registry-mirrors key with a list of mirror URLs. It's recommended to include multiple mirrors as performance can vary, and fallback to the next mirror in the list occurs if the primary one fails.

编辑文件：添加或修改 registry-mirrors 键，其中包含镜像 URL 的列表。建议包含多个镜像，因为性能可能有所差异，如果首选镜像失败，会自动尝试列表中的下一个。

{
"builder": {
    "gc": {
    "defaultKeepStorage": "20GB",
    "enabled": true
    }
},
"experimental": false,
"registry-mirrors": [
    "https://docker.hpcloud.cloud",
    "https://docker.m.daocloud.io",
    "https://docker.unsee.tech",
    "https://docker.1panel.live",
    "http://mirrors.ustc.edu.cn",
    "https://docker.chenby.cn",
    "http://mirror.azure.cn",
    "https://dockerpull.org",
    "https://dockerhub.icu",
    "https://hub.rat.dev"
]
}

Restart the Docker Daemon: After saving daemon.json, restart the Docker service to apply the changes.

重启 Docker 守护进程：保存 daemon.json 后，重启 Docker 服务以应用更改。
```
sudo systemctl daemon-reload
sudo systemctl restart docker
# Or, depending on your init system:
# sudo service docker restart
```

For Windows/macOS Users (Using Docker Desktop) | 对于 Windows/macOS 用户（使用 Docker Desktop）

Open Docker Desktop Settings: Click the Docker icon in the system tray (Windows) or menu bar (macOS) and select "Settings" (or "Preferences" on macOS). 打开 Docker Desktop 设置：点击系统托盘（Windows）或菜单栏（macOS）中的 Docker 图标，选择“Settings”（或 macOS 上的“Preferences”）。
Navigate to Docker Engine: In the Settings/Preferences window, select the "Docker Engine" tab from the sidebar. 导航到 Docker Engine：在设置/首偏好设置窗口中，从侧边栏选择“Docker Engine”选项卡。

Edit the JSON Configuration: This tab displays the daemon.json content in a text editor. Add or edit the registry-mirrors key as shown in the Linux example above. Ensure the JSON format remains valid. 编辑 JSON 配置：该选项卡在一个文本编辑器中显示 daemon.json 的内容。修改 registry-mirrors 键。确保 JSON 格式保持有效。

{
    // ... potentially other existing configurations
    "registry-mirrors": [
        "https://docker.hpcloud.cloud",
        "https://docker.m.daocloud.io",
        "https://docker.unsee.tech",
        "https://docker.1panel.live",
        "http://mirrors.ustc.edu.cn",
        "https://docker.chenby.cn",
        "http://mirror.azure.cn",
        "https://dockerpull.org",
        "https://dockerhub.icu",
        "https://hub.rat.dev"
    ]
    // ... potentially other existing configurations
}

Apply & Restart: Click the "Apply & Restart" button in the Docker Desktop window. 应用并重启：点击 Docker Desktop 窗口中的“Apply & Restart”按钮。

Verification | 验证

After restarting the Docker daemon, you can verify that your mirror configuration is loaded by running docker info in your terminal. Look for the Registry Mirrors line in the output.

重启 Docker 守护进程后，您可以在终端中运行 docker info 来验证您的镜像配置是否已加载。在输出中查找 Registry Mirrors 行。

docker info | grep -A 10 "Registry Mirrors"

The output should list the mirror URLs you configured. 输出应该列出您配置的镜像 URL。

Registry Mirrors:
 https://hub-mirror.lib.cqupt.edu.cn/
 https://docker.mirrors.ustc.edu.cn/
 https://mirrors.tuna.tsinghua.edu.cn/docker/
 https://YOUR_ALIYUN_MIRROR_ID.mirror.aliyuncs.com/

Now, when you execute docker pull <image_name>, Docker will attempt to pull from your configured mirrors first, significantly improving download speeds in most cases.

现在，当您执行 docker pull <镜像名称> 时，Docker 会优先尝试通过您配置的镜像仓库拉取，这在大多数情况下会显著提高下载速度。

Conclusion | 结论

Configuring Docker registry mirrors is an essential step for improving the efficiency and reliability of pulling public container images in mainland China. By directing traffic to local caches, network constraints are largely mitigated, leading to a smoother development and operational workflow. Users are encouraged to experiment with different available mirrors to identify which provides the best performance for their specific location and network environment.

配置 Docker 镜像仓库加速器是在中国大陆提高拉取公共容器镜像效率和可靠性的重要一步。通过将流量导向本地缓存，可以很大程度上缓解网络瓶颈，从而带来更流畅的开发和运维流程。建议用户尝试不同的可用镜像源，以确定哪个为其特定位置和网络环境提供最佳性能。